home *** CD-ROM | disk | FTP | other *** search
/ Visual Basic Controls / Visual Basic Controls.iso / vbcontrol / wmtrx32 / readme.txt < prev    next >
Encoding:
Text File  |  1997-11-16  |  7.5 KB  |  228 lines
  1. 0.Contents
  2.   --------
  3. 1.....Introduction
  4. 2.....Requirements
  5. 3.....List of files
  6. 4.....Installation
  7. 5.....Upon registration
  8. 6.....Usage
  9. 6.1...Generalities
  10. 6.2...Parameters
  11. 6.3...Operators
  12. 6.4...Return values
  13. 7.....Contacting the author
  14. 8.....Notice
  15.  
  16.  
  17. 1.Introduction
  18.   ------------
  19. This 32-bits DLL for Windows NT/95 implements a function that allows you
  20. various operations on matrices (determinant calculus, inversion, triangularization,
  21.  LU and QR decomposition's, addition, multiplication, transposition...).
  22.  
  23.  
  24. 2.Requirements
  25.   ------------
  26. A processor with Windows NT/95.
  27.  
  28.  
  29. 3.List of files
  30.   -------------
  31. The package includes the following files:
  32.    - README.1ST: a readme file to read before to begin with the
  33.                  installation
  34.    - README.TXT: this file
  35.    - LICENSE.TXT: the license agreement
  36.    - REGISTER.TXT: contains the information to register
  37.    - WMTRX32.DLL: the DLL file implementing the "matrix" function
  38.    - WMTRX32.H: the header file containing the prototype of the "matrix" function
  39.    - WMTRX32.LIB: the lib file to put with your library files and
  40.                   to include in your link parameters
  41.    - SETUP.EXE: the setup program file
  42.  
  43.  
  44. 4.Installation
  45.   ------------
  46. You can put the files in any directory. The only limitation is for
  47. running setup: you have to put SETUP.EXE and WMTRX32.DLL in the SAME
  48. directory.
  49. Simply run setup.exe. It will ask you for a registration key; leave
  50. the field to 0 for demo purpose.
  51. After a trial period of 30 days, the software will be disabled (RC=1) and
  52. you will have to register to continue using it (see register.txt).
  53.  
  54.  
  55. 5.Upon registration
  56.   -----------------
  57. Simply run setup.exe again and enter your registration key.
  58.  
  59.  
  60. 6.Usage
  61.   -----
  62. 6.1.Generalities
  63.     ------------
  64. As you should know, to use a DLL, you have to put it into the directory
  65. of your application, your path or your system directory (e. g. winnt\system32).
  66. This DLL implements the 'matrix' function whose prototype is as follows:
  67.  
  68. int matrix(char oper,double* mat1=NULL,unsigned long m=0,unsigned long n=0,
  69. double* mat2=NULL,unsigned long p=0,unsigned long q=0,double* res1=NULL,
  70. double* res2=NULL,unsigned long *np=NULL);
  71.  
  72. THE NECESSARY SPACE FOR RES1, RES2 AND NP MUST BE ALLOCATED IN THE CALLING 
  73. PROGRAM.
  74.  
  75. 6.2.Parameters
  76.     ----------
  77.     oper: operator; a character among the set {+,-,*,.,d,t,f,h,x,i,v}
  78.     mat1: a pointer to the 1st (m x n) matrix operand
  79.     m: the number of rows of mat1
  80.     n: the number of columns of mat1
  81.     mat2: a pointer to the 2nd (p x q) matrix operand (if applicable)
  82.     p: the number of rows of mat2
  83.     q: the number of columns of mat2
  84.     res1: a pointer to the 1st matrix of the result (see note 1)
  85.     res2: a pointer to the 2nd matrix of the result (if applicable) (see note 1)
  86.     np: a pointer to a ulong integer to retrieve the number of exchanged
  87.         lines (see note 1)
  88.  
  89. Note 1: for res1, res2 and np, no space is allocated through the 'matrix'
  90.         function. It is up to the calling program to allocate the
  91.         necessary space.
  92. Note 2: a scalar can be considered as a 1 by 1 matrix.
  93.  
  94. 6.3.Operators
  95.     ---------
  96.     + operator (addition)
  97.     ---------------------
  98.     Addition of 2 m by n matrices: C=A+B
  99.  
  100.     Sample call: ret=matrix('+',A,m,n,B,m,n,C);
  101.  
  102.     - operator (subtraction)
  103.     -------------------------
  104.     Subtraction of 2 m by n matrices: C=A-B
  105.  
  106.     Sample call: ret=matrix('-',A,m,n,B,m,n,C);
  107.  
  108.     * operator (multiplication of a matrix by another)
  109.     --------------------------------------------------
  110.     Multiplication of a m x n matrix A by a n x q matrix B: C=A*B
  111.  
  112.     Sample call: ret=matrix('*',A,m,n,B,n,q,C);
  113.  
  114.     . operator (multiplication of a matrix by a scalar)
  115.     ---------------------------------------------------
  116.     Multiplication of a m x n matrix A by a scalar a: B=a.A
  117.  
  118.     Sample call: ret=matrix('.',A,m,n,a,1,1,B);
  119.  
  120.     d operator (determinant computing)
  121.     ----------------------------------
  122.     Compute the determinant of the m x m matrix A and retrieve it in d: d=|A|
  123.  
  124.     Sample call: ret=matrix('d',A,m,m,NULL,0,0,d);
  125.  
  126.     t operator (triangularization)
  127.     ------------------------------
  128.     Triangularization of a m x m matrix A in an upper triangular matrix R.
  129.     Simple pivotation (exchange of lines) is used.
  130.  
  131.     In systems of linear equations, we have generally:
  132.          Ax=b (1)
  133.  
  134.     After transformation, (1) becomes:
  135.          Rx=c (2)
  136.  
  137.     So it is quite practical to be able to retrieve c.
  138.     You can obtain this by passing A as mat1, b as mat2; you will retrieve
  139.     R in res1 and c in res2.
  140.    
  141.     Sample call: ret=matrix('t',A,m,m,b,m,1,R,c) (here q=1 but it could be
  142.                  anything else);
  143.  
  144.     f operator (LU decomposition)
  145.     -----------------------------
  146.     Decomposition of a m x m matrix A in a lower triangular matrix L whose
  147.     all the diagonal elements are 1's and an upper triangular matrix U.
  148.     No pivoting methods are used in this factorization.
  149.  
  150.     The resulting matrix (res1) has the following form:
  151.  
  152.       u(1,1) u(1,2)........u(1,m)
  153.       l(2,1) u(2,2)........u(2,m)
  154.          .      .             .
  155.          .      .             .
  156.       l(m,1) l(m,2)........u(m,m)
  157.  
  158.     and l(i,i)=1 for 1=<i=<m
  159.  
  160.     THE 1ST ELEMENT (1st row, 1st column) OF A CANNOT BE 0.
  161.  
  162.     Sample call: ret=matrix('f',A,m,m,NULL,0,0,F);
  163.  
  164.     h operator (QR decomposition - Householder method)
  165.     --------------------------------------------------
  166.     Decomposition of a m x n (m >= n) matrix A in an unitary matrix Q and 
  167.     an upper triangular matrix R.
  168.     Q is stored in res1 and R in res2.
  169.  
  170.     Sample call: ret=matrix('h',A,m,n,NULL,0,0,Q,R);
  171.  
  172.     x operator (transposition)
  173.     --------------------------
  174.     Transpose the matrix m x n A and store the result in the n x m matrix B
  175.  
  176.     Sample call: ret=matrix('x',A,m,n,NULL,0,0,B);
  177.  
  178.     i operator (inversion)
  179.     ----------------------
  180.     Compute the inverse of the matrix m x m A and store the result in
  181.     the m x m matrix B.
  182.  
  183.     THERE IS NO CHECK ON THE VALUE OF THE DETERMINANT (must not be null)
  184.     IMPLEMENTED IN THIS FUNCTION. IT IS UP TO THE USER TO CHECK IT FIRST!
  185.  
  186.     Sample call: ret=matrix('i',A,m,m,NULL,0,0,B);
  187.  
  188.     v operator (pivot)
  189.     ---------------------
  190.     Line exchanges on a m x m matrix A to obtain a matrix C whose the diagonal
  191.     element (i,i) with i>=1 is such that its absolute value is the maximum of the 
  192.     elements of the i-th column of the m-i+1 x m-i+1 sub-matrix.
  193.  
  194.     If another matrix B is passed as mat2, the permutation matrix applied on A
  195.     will also be applied on it and the resulting matrix will be found in res2.
  196.  
  197.     Sample call: ret=matrix('v',A,m,m,B,m,q,C,D);
  198.  
  199.  
  200. 6.4.Return values
  201.     -------------
  202.      0: normal completion.
  203.      1: your trial period has expired; you have now to register
  204.         (see register.txt for more information's).
  205.      2: division by 0.
  206.      4: the 1st element of the matrix (1st row, 1st column) is 0;
  207.         exchange lines and/or columns to avoid it. This return code
  208.         can happen only in LU factorization.
  209.      8: dimensions don't match.
  210.     12: missing or invalid parameter(s).
  211.     16: invalid operator.
  212.     24: memory allocation failure.
  213.  
  214.  
  215. 7.Contacting the author
  216.   ---------------------
  217. You can contact the author at the following location:
  218.  
  219.             Serge COLLIN
  220.             rue Montoyer 37/3
  221.             B-1000 Brussels
  222.             BELGIUM (Europe)
  223.             e-mail: sergecollin@hotmail.com
  224.  
  225.  
  226. 8.Notice
  227.   ------
  228. Windows 95 and Windows NT are trademarks of Microsoft Inc.